VersionEdit is a software development tool which automatically creates and updates product version information throughout the life of a software product.
As an alternative to using ResEdit or Rez, VersionEdit can be used to create and intelligently increment 'vers' type resources that adhere to Apple’s version guidelines. VersionEdit also allows developers to encapsulate additional information about the product and their company within the application, making it available for use by other utilities.
The interface is simple and straightforward, allowing the developer to supply information step by step. For the novice, VersionEdit helps insure the correct information is entered and displayed properly. For the advanced user, it can save time usually spent switching between ResEdit and Finder while verifying the changes.
WHAT’S NEW IN VERSION 1.1?
It has been over a year since the initial release of VersionEdit, and though we haven’t received much feedback from outside sources who are using it (or not using it), it has served us here at Teknosys, Inc. (as well as myself personally) extremely well. Considering this kind of performance record, we’ve only made a few minor changes to bring VersionEdit up–to–date and make it more useful.
• The AppleLink address field has been renamed eWorld.
For most AppleLink subscribers, their accounts will soon be automatically transferred to eWorld. VersionEdit 1.1 reflects and supports this change transparently by simply reusing the AppleLink address field for eWorld.
• A Finder balloon help resource is automatically added to files which do not already have one.
VersionEdit adds a special 'hfdr' -5696 resource to your file (if it does not already have one) which points to the existing product description 'TEXT' resource created and maintained by VersionEdit. This means your product description information is automatically being used by the Finder to display balloon help for your icon, as well as by utilities (such as Casady & Green’s Conflict Catcher™) which use this resource to locate and display information about your file.
• The Product Information API and ResEdit Templates have been updated.
If you are using source code from Product Information API with your product, be sure to use these new updates. The ResEdit templates have been altered to reflect the changes from AppleLink to eWorld.
Please feel free to make requests for future enhancements!
BACKGROUND
In establishing a knowledgebase of Macintosh software information for our Help! product, we collect many types of information about software files. Traditionally, 'vers' 1 and 'vers' 2 resources have been a fairly reliable place to find out about a product’s version number, and company or author name. And Apple has fairly good guidelines about the format of these resources, how version numbers are to be used, and how they are displayed within the Finder.
Unfortunately, these guidelines are rarely followed completely or at all. We have found there to be an endless number of version numbering schemes, many of which have little meaning to anyone except the vendor. Though the main purpose of version numbers is to tell the difference between older and newer revisions of software, Apple’s guidelines also provide a standard method for specifying what kinds of changes have been made, and whether these changes have been completed and officially released. By adopting these guidelines, your users will have a better understanding of how a software update will affect them. VersionEdit makes adopting Apple’s guidelines a little bit easier.
Refer to Inside Macintosh Volume VI and Inside Macintosh: Toolbox Essentials for additional documentation on the subject of version information resources.
VERSIONEDIT RESOURCES
VersionEdit creates and modifies the following resources:
Use the product information dialog to edit information about the product. None of these fields should be left blank.
The product information resource is a 'STR#' and contains the following strings in order:
file name - This is the file’s original file name. This could be used by a utility to help identify a file or restore the file’s original name in the event that it has been changed.
product name - The name of the specific product with which this file belongs. This can be the same as the file name if the file is the product. The product name is used to automatically update the message for the product version ('vers' 2) resource.
release year - The most recent year in which the product was released. A range of years, such as “1991-1994”, is acceptable to represent how long the product has been in release. The release year is used to automatically update the message for the file version ('vers' 1) resource.
VENDOR INFORMATION
Use the vendor information dialog to edit information about the product’s vendor. This information could be used by a utility to inform users of who to contact for updates or support. If information cannot be supplied for some of the fields, they should be left blank.
The vendor information resource is a 'STR#' and contains the following strings in order:
author name - This is the name of the author of the file.
company name - This is the name of the company or organization who created the file.
address - This is the full mailing address of the vendor.
phone number - This is the telephone number of the vendor.
fax number - This is the fax number of the vendor.
America Online address - This is the America Online screen name of the vendor.
CompuServe address - This is the CompuServe address of the vendor.
eWorld address - This is the eWorld screen name of the vendor (formerly AppleLink address).
Internet address - This is the Internet address of the vendor.
PRODUCT VERSION
The product version dialog lets you specify and update version information for the product with which the file was released. If the file does not belong with a larger group of files, its product version should be the same as its file version.
All files released as part of a product should have the same product version information; use the Copy From… button to copy this information from another file belonging to the same product.
Changing any part of the version number will automatically update the number and message fields using the recommended format. Clicking the Update button will manually update the number and message fields using currently available information. Make sure to do this after changing the product name in the product information dialog.
To undo any changes made to information in the product version dialog, click the Revert button. The dialog will return to its original state.
To automatically increment the version, you can use one of the radio buttons in the Auto Increment section of the dialog.
Click the Change button to keep the changes you have made. An alert gives you the option of automatically updating the file version information to match the new product version. Holding down the option key when clicking the Change button or pressing return will update the file version without asking.
The information in this dialog is saved as a 'vers' 2 resource.
RELEASE DATE
You may only change the release date for a file if you are editing the file itself; this information cannot be saved into a resource file. Changes made to the date in this dialog are saved into the file’s creation and modification date information.
The time for the release date is always set to 12:00 PM.
By default, the file’s modification date is used. Click the Today button to use the current date.
PRODUCT DESCRIPTION
Use the description dialog to add a brief explanation of what the file is or does. This information should be as brief as possible and should not be used as a substitute for a “read me” file. This information is intended to be read by utilities or BBS host software to offer a short abstract. Though the maximum allowable length of the description is 32K bytes, a length of 480 bytes or less is recommended.
The product description is saved as a 'TEXT' 1 resource.
If your file does not already contain a 'hfdr' -5696 resource, VersionEdit will automatically add one for you which points to the 'TEXT' 1 resource created and maintained by VersionEdit. This resource is used by the Finder to display balloon help for your file’s icon, and is also used by various utilities (such as Casady & Green’s Conflict Catcher™) to provide a brief description about your file.
FILE VERSION
Use the file version dialog to specify and update version information for the file. This dialog behaves similarly to the product version dialog with the omission of the Copy From button.
The information supplied in this dialog is saved as a 'vers' 1 resource.
SIZE SETTINGS
Use the SIZE settings dialog to declare specific system requirements of an application. This dialog provides an intuitive way to modify this information by using groups of related check boxes and radio buttons.
SIZE resources can only be edited for applications or ResEdit files; for other types of files the SIZE Info button is disabled.
The SIZE settings are saved as a 'SIZE' -1 resource.
Refer to Inside Macintosh Volume VI and Inside Macintosh: Toolbox Essentials for additional documentation on the subject of SIZE resources.
APPENDIX
A: ResEdit Templates
The file VersionEdit Templates.rsrc has been included as an alternate method of viewing and editing the product and vendor information resources ('STR#' 1 & 2). As these resources are 'STR#' resources, please make sure that the count field reflects the actual number of fields available.
B: Accessing VersionEdit Information
A set of source files written in C have been included with VersionEdit. These files, when included info a project of your own, will give you most of the basic tools you need to access the information generated by VersionEdit.
Since product and file information resources are 'STR#' resources, enumerations have been defined to access this information through the toolbox function GetIndString().
For example, to access the product name you would use:
In addition, three functions have been provided to allow more convenient access to the information stored in the 'vers' resources. These functions may be compiled and used in your project, or you can use them as examples of how to write your own.
VersionEdit is FREE, written with the hope that if developers had a more convenient way to create and update version information for their products, they would use it. VersionEdit may be distributed to anyone by any means as long as it remains unaltered, is accompanied by this and all other associated files, and is not sold for profit.
QUESTIONS, COMMENTS & SUGGESTIONS
Please direct correspondence regarding VersionEdit to:
